home *** CD-ROM | disk | FTP | other *** search
/ Chip 2007 January, February, March & April / Chip-Cover-CD-2007-02.iso / Pakiet bezpieczenstwa / mini Pentoo LiveCD 2006.1 / mpentoo-2006.1.iso / livecd.squashfs / usr / include / gaim / util.h < prev    next >
C/C++ Source or Header  |  2005-10-18  |  24KB  |  789 lines
  1. /**
  2.  * @file util.h Utility Functions
  3.  * @ingroup core
  4.  *
  5.  * gaim
  6.  *
  7.  * Gaim is the legal property of its developers, whose names are too numerous
  8.  * to list here.  Please refer to the COPYRIGHT file distributed with this
  9.  * source distribution.
  10.  *
  11.  * This program is free software; you can redistribute it and/or modify
  12.  * it under the terms of the GNU General Public License as published by
  13.  * the Free Software Foundation; either version 2 of the License, or
  14.  * (at your option) any later version.
  15.  *
  16.  * This program is distributed in the hope that it will be useful,
  17.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19.  * GNU General Public License for more details.
  20.  *
  21.  * You should have received a copy of the GNU General Public License
  22.  * along with this program; if not, write to the Free Software
  23.  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  24.  *
  25.  * @todo Rename the functions so that they live somewhere in the gaim
  26.  *       namespace.
  27.  */
  28. #ifndef _GAIM_UTIL_H_
  29. #define _GAIM_UTIL_H_
  30.  
  31. #include <stdio.h>
  32.  
  33. #include "account.h"
  34.  
  35. #ifdef __cplusplus
  36. extern "C" {
  37. #endif
  38.  
  39. /**************************************************************************/
  40. /** @name Base16 Functions                                                */
  41. /**************************************************************************/
  42. /*@{*/
  43.  
  44. /**
  45.  * Converts a string to its base-16 equivalent.
  46.  *
  47.  * @param str The string to convert.
  48.  * @param len The length of the string.
  49.  *
  50.  * @return The base-16 string.
  51.  *
  52.  * @see gaim_base16_decode()
  53.  */
  54. unsigned char *gaim_base16_encode(const unsigned char *str, int len);
  55.  
  56. /**
  57.  * Converts a string back from its base-16 equivalent.
  58.  *
  59.  * @param str     The string to convert back.
  60.  * @param ret_str The returned, non-base-16 string.
  61.  *
  62.  * @return The length of the returned string.
  63.  *
  64.  * @see gaim_base16_encode()
  65.  */
  66. int gaim_base16_decode(const char *str, unsigned char **ret_str);
  67.  
  68. /*@}*/
  69.  
  70.  
  71. /**************************************************************************/
  72. /** @name Base64 Functions                                                */
  73. /**************************************************************************/
  74. /*@{*/
  75.  
  76. /**
  77.  * Converts a string to its base-64 equivalent.
  78.  *
  79.  * @param buf The data to convert.
  80.  * @param len The length of the data.
  81.  *
  82.  * @return The base-64 version of @a str.
  83.  *
  84.  * @see gaim_base64_decode()
  85.  */
  86. unsigned char *gaim_base64_encode(const unsigned char *buf, size_t len);
  87.  
  88. /**
  89.  * Converts a string back from its base-64 equivalent.
  90.  *
  91.  * @param str     The string to convert back.
  92.  * @param ret_str The returned, non-base-64 string.
  93.  * @param ret_len The returned string length.
  94.  *
  95.  * @see gaim_base64_encode()
  96.  */
  97. void gaim_base64_decode(const char *str, char **ret_str, int *ret_len);
  98.  
  99. /*@}*/
  100.  
  101. /**************************************************************************/
  102. /** @name Quoted Printable Functions                                      */
  103. /**************************************************************************/
  104. /*@{*/
  105.  
  106. /**
  107.  * Converts a quoted printable string back to its readable equivalent.
  108.  *
  109.  * @param str     The string to convert back.
  110.  * @param ret_str The returned, readable string.
  111.  * @param ret_len The returned string length.
  112.  */
  113. void gaim_quotedp_decode (const char *str, char **ret_str, int *ret_len);
  114.  
  115. /*@}*/
  116.  
  117. /**************************************************************************/
  118. /** @name MIME Functions                                                  */
  119. /**************************************************************************/
  120. /*@{*/
  121.  
  122. /**
  123.  * Converts a MIME header field string back to its readable equivalent
  124.  * according to RFC 2047.  Basically, a header is plain ASCII and can
  125.  * contain any number of sections called "encoded-words."  The format
  126.  * of an encoded word is =?ISO-8859-1?Q?Keld_J=F8rn_Simonsen?=
  127.  * =? designates the beginning of the encoded-word
  128.  * ?= designates the end of the encoded-word
  129.  * ? segments the encoded word into three pieces.  The first piece is
  130.  *   the character set, the second piece is the encoding, and the
  131.  *   third piece is the encoded text.
  132.  *
  133.  * @param str The string to convert back.
  134.  *
  135.  * @return The readable string.
  136.  */
  137. char *gaim_mime_decode_field (const char *str);
  138.  
  139. /*@}*/
  140.  
  141.  
  142. /**************************************************************************/
  143. /** @name Date/Time Functions                                             */
  144. /**************************************************************************/
  145. /*@{*/
  146.  
  147. /**
  148.  * Returns the current local time in hour:minute:second form.
  149.  *
  150.  * The returned string is stored in a static buffer, so the result
  151.  * should be g_strdup()'d if it's intended to be used for long.
  152.  *
  153.  * @return The current local time.
  154.  *
  155.  * @see gaim_date_full()
  156.  */
  157. const char *gaim_date(void);
  158.  
  159. /**
  160.  * Returns the date and time in human-readable form.
  161.  *
  162.  * The returned string is stored in a static buffer, so the result
  163.  * should be g_strdup()'d if it's intended to be used for long.
  164.  *
  165.  * @return The date and time in human-readable form.
  166.  *
  167.  * @see gaim_date()
  168.  */
  169. const char *gaim_date_full(void);
  170.  
  171. /**
  172.  * Builds a time_t from the supplied information.
  173.  *
  174.  * @param year  The year.
  175.  * @param month The month.
  176.  * @param day   The day.
  177.  * @param hour  The hour.
  178.  * @param min   The minute.
  179.  * @param sec   The second.
  180.  *
  181.  * @return A time_t.
  182.  */
  183. time_t gaim_time_build(int year, int month, int day, int hour,
  184.                        int min, int sec);
  185.  
  186. /**
  187.  * Parses a timestamp in jabber or ISO8601 format and returns a time_t.
  188.  *
  189.  * @param timestamp The timestamp
  190.  * @param utc Assume UTC if no timezone specified
  191.  *
  192.  * @return A time_t.
  193.  */
  194. time_t gaim_str_to_time(const char *timestamp, gboolean utc);
  195.  
  196. /*@}*/
  197.  
  198.  
  199. /**************************************************************************/
  200. /** @name Markup Functions                                                */
  201. /**************************************************************************/
  202. /*@{*/
  203.  
  204. /**
  205.  * Finds a HTML tag matching the given name.
  206.  *
  207.  * This locates an HTML tag's start and end, and stores its attributes
  208.  * in a GData hash table. The names of the attributes are lower-cased
  209.  * in the hash table, and the name of the tag is case insensitive.
  210.  *
  211.  * @param needle    the name of the tag
  212.  * @param haystack    the null-delimited string to search in
  213.  * @param start        a pointer to the start of the tag if found
  214.  * @param end        a pointer to the end of the tag if found
  215.  * @param attributes    the attributes, if the tag was found
  216.  * @return TRUE if the tag was found
  217.  */
  218. gboolean gaim_markup_find_tag(const char *needle, const char *haystack,
  219.                               const char **start, const char **end,
  220.                               GData **attributes);
  221.  
  222. /**
  223.  * Extracts a field of data from HTML.
  224.  *
  225.  * This is a scary function. See protocols/msn/msn.c and
  226.  * protocols/yahoo/yahoo_profile.c for example usage.
  227.  *
  228.  * @param str            The string to parse.
  229.  * @param len            The size of str.
  230.  * @param dest           The destination GString to append the new
  231.  *                       field info to.
  232.  * @param start_token    The beginning token.
  233.  * @param skip           The number of characters to skip after the
  234.  *                       start token.
  235.  * @param end_token      The ending token.
  236.  * @param check_value    The value that the last character must meet.
  237.  * @param no_value_token The token indicating no value is given.
  238.  * @param display_name   The short descriptive name to display for this token.
  239.  * @param is_link        TRUE if this should be a link, or FALSE otherwise.
  240.  * @param link_prefix    The prefix for the link.
  241.  *
  242.  * @return TRUE if successful, or FALSE otherwise.
  243.  */
  244. gboolean gaim_markup_extract_info_field(const char *str, int len, GString *dest,
  245.                                         const char *start_token, int skip,
  246.                                         const char *end_token, char check_value,
  247.                                         const char *no_value_token,
  248.                                         const char *display_name, gboolean is_link,
  249.                                         const char *link_prefix);
  250.  
  251. /**
  252.  * Converts HTML markup to XHTML.
  253.  *
  254.  * @param html       The HTML markup.
  255.  * @param dest_xhtml The destination XHTML output.
  256.  * @param dest_plain The destination plain-text output.
  257.  */
  258. void gaim_markup_html_to_xhtml(const char *html, char **dest_xhtml,
  259.                                char **dest_plain);
  260.  
  261. /**
  262.  * Strips HTML tags from a string.
  263.  *
  264.  * @param str The string to strip HTML from.
  265.  *
  266.  * @return The new string without HTML. This must be freed.
  267.  */
  268. char *gaim_markup_strip_html(const char *str);
  269.  
  270. /**
  271.  * Adds the necessary HTML code to turn URIs into HTML links in a string.
  272.  *
  273.  * @param str The string to linkify.
  274.  *
  275.  * @return The linkified text.
  276.  */
  277. char *gaim_markup_linkify(const char *str);
  278.  
  279. /**
  280.  * Escapes HTML special characters to be displayed literally.
  281.  * For example '&' is replaced by "&" and so on
  282.  *
  283.  * @param html The string in which to escape any HTML special characters
  284.  *
  285.  * @return the text with HTML special characters escaped
  286.  */
  287. char *gaim_escape_html(const char *html);
  288.  
  289. /**
  290.  * Unescapes HTML entities to their literal characters.
  291.  * For example "&" is replaced by '&' and so on.
  292.  * Actually only "&", """, "<" and ">" are currently
  293.  * supported.
  294.  *
  295.  * @param html The string in which to unescape any HTML entities
  296.  *
  297.  * @return the text with HTML entities literalized
  298.  */
  299. char *gaim_unescape_html(const char *html);
  300.  
  301. /**
  302.  * Returns a newly allocated substring of the HTML UTF-8 string "str".
  303.  * The markup is preserved such that the substring will have the same
  304.  * formatting as original string, even though some tags may have been
  305.  * opened before "x", or may close after "y". All open tags are closed
  306.  * at the end of the returned string, in the proper order.
  307.  *
  308.  * Note that x and y are in character offsets, not byte offsets, and
  309.  * are offsets into an unformatted version of str. Because of this,
  310.  * this function may be sensitive to changes in GtkIMHtml and may break
  311.  * when used with other UI's. libgaim users are encouraged to report and
  312.  * work out any problems encountered.
  313.  *
  314.  * @param str The input NUL terminated, HTML, UTF-8 (or ASCII) string.
  315.  * @param x The character offset into an unformatted version of str to
  316.  *          begin at.
  317.  * @param y The character offset (into an unformatted vesion of str) of
  318.  *          one past the last character to include in the slice.
  319.  *
  320.  * @return The HTML slice of string, with all formatting retained.
  321.  */
  322. char *gaim_markup_slice(const char *str, guint x, guint y);
  323.  
  324. /**
  325.  * Returns a newly allocated string containing the name of the tag
  326.  * located at "tag". Tag is expected to point to a '<', and contain
  327.  * a '>' sometime after that. If there is no '>' and the string is
  328.  * not NUL terminated, this function can be expected to segfault.
  329.  *
  330.  * @param tag The string starting a HTML tag.
  331.  * @return A string containing the name of the tag.
  332.  */
  333. char *gaim_markup_get_tag_name(const char *tag);
  334.  
  335. /*@}*/
  336.  
  337.  
  338. /**************************************************************************/
  339. /** @name Path/Filename Functions                                         */
  340. /**************************************************************************/
  341. /*@{*/
  342.  
  343. /**
  344.  * Returns the user's home directory.
  345.  *
  346.  * @return The user's home directory.
  347.  *
  348.  * @see gaim_user_dir()
  349.  */
  350. const gchar *gaim_home_dir(void);
  351.  
  352. /**
  353.  * Returns the gaim settings directory in the user's home directory.
  354.  *
  355.  * @return The gaim settings directory.
  356.  *
  357.  * @see gaim_home_dir()
  358.  */
  359. char *gaim_user_dir(void);
  360.  
  361. /**
  362.  * Define a custom gaim settings directory, overriding the default (user's home directory/.gaim)
  363.  * @param dir The custom settings directory
  364.  */
  365. void set_gaim_user_dir(const char *dir);
  366.  
  367. /**
  368.  * Builds a complete path from the root, making any directories along
  369.  * the path which do not already exist.
  370.  *
  371.  * @param path The path you wish to create.  Note that it must start
  372.  *        from the root or this function will fail.
  373.  * @param mode Unix-style permissions for this directory.
  374.  *
  375.  * @return 0 for success, nonzero on any error.
  376.  */
  377. int gaim_build_dir(const char *path, int mode);
  378.  
  379. /**
  380.  * Creates a temporary file and returns a file pointer to it.
  381.  *
  382.  * This is like mkstemp(), but returns a file pointer and uses a
  383.  * pre-set template. It uses the semantics of tempnam() for the
  384.  * directory to use and allocates the space for the file path.
  385.  *
  386.  * The caller is responsible for closing the file and removing it when
  387.  * done, as well as freeing the space pointed to by @a path with
  388.  * g_free().
  389.  *
  390.  * @param path The returned path to the temp file.
  391.  *
  392.  * @return A file pointer to the temporary file, or @c NULL on failure.
  393.  */
  394. FILE *gaim_mkstemp(char **path);
  395.  
  396. /**
  397.  * Checks if the given program name is valid and executable.
  398.  *
  399.  * @param program The file name of the application.
  400.  *
  401.  * @return True if the program is runable.
  402.  */
  403. gboolean gaim_program_is_valid(const char *program);
  404.  
  405. /**
  406.  * Returns the IP address from a socket file descriptor.
  407.  *
  408.  * @param fd The socket file descriptor.
  409.  *
  410.  * @return The IP address, or @c NULL on error.
  411.  */
  412. char *gaim_fd_get_ip(int fd);
  413.  
  414. /*@}*/
  415.  
  416.  
  417. /**************************************************************************/
  418. /** @name String Functions                                                */
  419. /**************************************************************************/
  420. /*@{*/
  421.  
  422. /**
  423.  * Normalizes a string, so that it is suitable for comparison.
  424.  *
  425.  * The returned string will point to a static buffer, so if the
  426.  * string is intended to be kept long-term, you <i>must</i>
  427.  * g_strdup() it. Also, calling normalize() twice in the same line
  428.  * will lead to problems.
  429.  *
  430.  * @param account  The account the string belongs to.
  431.  * @param str      The string to normalize.
  432.  *
  433.  * @return A pointer to the normalized version stored in a static buffer.
  434.  */
  435. const char *gaim_normalize(const GaimAccount *account, const char *str);
  436.  
  437. /**
  438.  * Normalizes a string, so that it is suitable for comparison.
  439.  *
  440.  * This is one possible implementation for the PRPL callback
  441.  * function "normalize."  It returns a lowercase and UTF-8
  442.  * normalized version of the string.
  443.  *
  444.  * @param account  The account the string belongs to.
  445.  * @param str      The string to normalize.
  446.  *
  447.  * @return A pointer to the normalized version stored in a static buffer.
  448.  */
  449. const char *gaim_normalize_nocase(const GaimAccount *account, const char *str);
  450.  
  451. /**
  452.  * Compares two strings to see if the first contains the second as
  453.  * a proper prefix.
  454.  *
  455.  * @param s  The string to check.
  456.  * @param p  The prefix in question.
  457.  *
  458.  * @return   TRUE if p is a prefix of s, otherwise FALSE.
  459.  */
  460. gboolean gaim_str_has_prefix(const char *s, const char *p);
  461.  
  462. /**
  463.  * Compares two strings to see if the second is a proper suffix
  464.  * of the first.
  465.  *
  466.  * @param s  The string to check.
  467.  * @param x  The suffix in question.
  468.  *
  469.  * @return   TRUE if x is a a suffix of s, otherwise FALSE.
  470.  */
  471. gboolean gaim_str_has_suffix(const char *s, const char *x);
  472.  
  473. /**
  474.  * Looks for %n, %d, or %t in a string, and replaces them with the
  475.  * specified name, date, and time, respectively.
  476.  *
  477.  * @param str  The string that may contain the special variables.
  478.  * @param name The sender name.
  479.  *
  480.  * @return A newly allocated string where the special variables are
  481.  *         expanded.  This should be g_free'd by the caller.
  482.  */
  483. gchar *gaim_str_sub_away_formatters(const char *str, const char *name);
  484.  
  485. /**
  486.  * Duplicates a string and replaces all newline characters from the
  487.  * source string with HTML linebreaks.
  488.  *
  489.  * @param src The source string.
  490.  *
  491.  * @return The new string.  Must be g_free'd by the caller.
  492.  */
  493. gchar *gaim_strdup_withhtml(const gchar *src);
  494.  
  495. /**
  496.  * Ensures that all linefeeds have a matching carriage return.
  497.  *
  498.  * @param str The source string.
  499.  *
  500.  * @return The string with carriage returns.
  501.  */
  502. char *gaim_str_add_cr(const char *str);
  503.  
  504. /**
  505.  * Strips all carriage returns from a string.
  506.  *
  507.  * @param str The string to strip carriage returns from.
  508.  */
  509. void gaim_str_strip_cr(char *str);
  510.  
  511. /**
  512.  * Given a string, this replaces one substring with another
  513.  * and returns a newly allocated string.
  514.  *
  515.  * @param string The string from which to replace stuff.
  516.  * @param delimiter The substring you want replaced.
  517.  * @param replacement The substring you want inserted in place
  518.  *        of the delimiting substring.
  519.  *
  520.  * @return A new string, after performing the substitution.
  521.  *         free this with g_free().
  522.  */
  523. gchar *gaim_strreplace(const char *string, const char *delimiter,
  524.                        const char *replacement);
  525.  
  526. /**
  527.  * Given a string, this replaces any numerical character references
  528.  * in that string with the corresponding actual utf-8 substrings,
  529.  * and returns a newly allocated string.
  530.  *
  531.  * @param in The string which might contain numerical character references.
  532.  *
  533.  * @return A new string, with numerical character references
  534.  *         replaced with actual utf-8, free this with g_free().
  535.  */
  536. char *gaim_utf8_ncr_decode(const char *in);
  537.  
  538. /**
  539.  * Given a string, this replaces one substring with another
  540.  * ignoring case and returns a newly allocated string.
  541.  *
  542.  * @param string The string from which to replace stuff.
  543.  * @param delimiter The substring you want replaced.
  544.  * @param replacement The substring you want inserted in place
  545.  *        of the delimiting substring.
  546.  *
  547.  * @return A new string, after performing the substitution.
  548.  *         free this with g_free().
  549.  */
  550. gchar *gaim_strcasereplace(const char *string, const char *delimiter,
  551.                            const char *replacement);
  552.  
  553. /**
  554.  * This is like strstr, except that it ignores ASCII case in
  555.  * searching for the substring.
  556.  *
  557.  * @param haystack The string to search in.
  558.  * @param needle   The substring to find.
  559.  *
  560.  * @return the location of the substring if found, or NULL if not
  561.  */
  562. const char *gaim_strcasestr(const char *haystack, const char *needle);
  563.  
  564. /**
  565.  * Returns a string representing a filesize in the appropriate
  566.  * units (MB, KB, GB, etc.)
  567.  *
  568.  * @param size The size
  569.  *
  570.  * @return The string in units form. This must be freed.
  571.  */
  572. char *gaim_str_size_to_units(size_t size);
  573.  
  574. /**
  575.  * Converts seconds into a human-readable form.
  576.  *
  577.  * @param sec The seconds.
  578.  *
  579.  * @return A human-readable form, containing days, hours, minutes, and
  580.  *         seconds.
  581.  */
  582. char *gaim_str_seconds_to_string(guint sec);
  583.  
  584. /**
  585.  * Converts a binary string into a NUL terminated ascii string,
  586.  * replacing nonascii characters and characters below SPACE (including
  587.  * NUL) into \\xyy, where yy are two hex digits. Also backslashes are
  588.  * changed into two backslashes (\\\\). The returned, newly allocated
  589.  * string can be outputted to the console, and must be g_free()d.
  590.  *
  591.  * @param binary A string of random data, possibly with embedded NULs
  592.  *               and such.
  593.  * @param len The length in bytes of the input string. Must not be 0.
  594.  *
  595.  * @return A newly allocated ASCIIZ string.
  596.  */
  597. char *gaim_str_binary_to_ascii(const unsigned char *binary, guint len);
  598. /*@}*/
  599.  
  600.  
  601. /**************************************************************************/
  602. /** @name URI/URL Functions                                               */
  603. /**************************************************************************/
  604. /*@{*/
  605.  
  606. /**
  607.  * Parses a URL, returning its host, port, file path, username and password.
  608.  *
  609.  * The returned data must be freed.
  610.  *
  611.  * @param url      The URL to parse.
  612.  * @param ret_host The returned host.
  613.  * @param ret_port The returned port.
  614.  * @param ret_path The returned path.
  615.  * @param ret_user The returned username.
  616.  * @param ret_passwd The returned password.
  617.  */
  618. gboolean gaim_url_parse(const char *url, char **ret_host, int *ret_port,
  619.                         char **ret_path, char **ret_user, char **ret_passwd);
  620.  
  621. /**
  622.  * Fetches the data from a URL, and passes it to a callback function.
  623.  *
  624.  * @param url        The URL.
  625.  * @param full       TRUE if this is the full URL, or FALSE if it's a
  626.  *                   partial URL.
  627.  * @param user_agent The user agent field to use, or NULL.
  628.  * @param http11     TRUE if HTTP/1.1 should be used to download the file.
  629.  * @param cb         The callback function.
  630.  * @param data       The user data to pass to the callback function.
  631.  */
  632. void gaim_url_fetch(const char *url, gboolean full,
  633.                     const char *user_agent, gboolean http11,
  634.                     void (*cb)(void *, const char *, size_t),
  635.                     void *data);
  636. /**
  637.  * Decodes a URL into a plain string.
  638.  *
  639.  * This will change hex codes and such to their ascii equivalents.
  640.  *
  641.  * @param str The string to translate.
  642.  *
  643.  * @return The resulting string.
  644.  */
  645. const char *gaim_url_decode(const char *str);
  646.  
  647. /**
  648.  * Encodes a URL into an escaped string.
  649.  *
  650.  * This will change non-alphanumeric characters to hex codes.
  651.  *
  652.  * @param str The string to translate.
  653.  *
  654.  * @return The resulting string.
  655.  */
  656. const char *gaim_url_encode(const char *str);
  657.  
  658. /**
  659.  * Checks if the given email address is syntactically valid.
  660.  *
  661.  * @param address The email address to validate.
  662.  *
  663.  * @return True if the email address is syntactically correct.
  664.  */
  665. gboolean gaim_email_is_valid(const char *address);
  666.  
  667. /**
  668.  * This function extracts a list of URIs from the a "text/uri-list" string
  669.  * It was "borrowed" from gnome_uri_list_extract_uris
  670.  * 
  671.  * @param uri_list an uri-list in the standard format.
  672.  *
  673.  * @return a GList containing strings allocated with g_malloc that have been 
  674.  *    splitted from uri-list.
  675.  */
  676. GList* gaim_uri_list_extract_uris (const gchar* uri_list);
  677.  
  678. /**
  679.  * This function extracts a list of filenames from the a "text/uri-list" string
  680.  * It was "borrowed" from gnome_uri_list_extract_filenames
  681.  * 
  682.  * @param uri_list an uri-list in the standard format.
  683.  *
  684.  * @return a GList containing strings allocated with g_malloc that contain the 
  685.  *     filenames in the uri-list. Note that unlike gaim_uri_list_extract_uris() 
  686.  *     function, this will discard any non-file uri from the result value.
  687.  */
  688. GList* gaim_uri_list_extract_filenames (const gchar* uri_list);
  689.  
  690. /*@}*/
  691.  
  692. /**************************************************************************
  693.  * UTF8 String Functions
  694.  **************************************************************************/
  695. /*@{*/
  696.  
  697. /**
  698.  * Attempts to convert a string to UTF-8 from an unknown encoding.
  699.  *
  700.  * This function checks the locale and tries sane defaults.
  701.  *
  702.  * @param str The source string.
  703.  *
  704.  * @return The UTF-8 string, or @c NULL if it could not be converted.
  705.  */
  706. gchar *gaim_utf8_try_convert(const char *str);
  707.  
  708. /**
  709.  * Salvages the valid UTF-8 characters from a string, replacing any
  710.  * invalid characters with a filler character (currently hardcoded to
  711.  * '?').
  712.  *
  713.  * @param str The source string.
  714.  *
  715.  * @return A valid UTF-8 string.
  716.  */
  717. gchar *gaim_utf8_salvage(const char *str);
  718.  
  719. /**
  720.  * Compares two UTF-8 strings.
  721.  *
  722.  * @param a The first string.
  723.  * @param b The second string.
  724.  *
  725.  * @return -1 if @a is less than @a b.
  726.  *          0 if @a is equal to @a b.
  727.  *          1 if @a is greater than @a b.
  728.  */
  729. int gaim_utf8_strcasecmp(const char *a, const char *b);
  730.  
  731. /**
  732.  * Checks for messages starting with "/me "
  733.  *
  734.  * @param message The message to check
  735.  * @param len     The message length, or -1
  736.  *
  737.  * @return TRUE if it starts with /me, and it has been removed, otherwise FALSE
  738.  */
  739. gboolean gaim_message_meify(char *message, size_t len);
  740.  
  741. /**
  742.  * Removes the underscore characters from a string used identify the mnemonic
  743.  * character.
  744.  *
  745.  * @param in  The string to strip
  746.  *
  747.  * @return The stripped string
  748.  */
  749. char *gaim_text_strip_mnemonic(const char *in);
  750.  
  751. /*@}*/
  752.  
  753. /**
  754.  * Adds 8 to something.
  755.  *
  756.  * Blame SimGuy.
  757.  *
  758.  * @param x The number to add 8 to.
  759.  *
  760.  * @return x + 8
  761.  */
  762. #define gaim_add_eight(x) ((x)+8)
  763.  
  764. /**
  765.  * Does the reverse of gaim_escape_filename
  766.  *
  767.  * This will change hex codes and such to their ascii equivalents.
  768.  *
  769.  * @param str The string to translate.
  770.  *
  771.  * @return The resulting string.
  772.  */
  773. const char *gaim_unescape_filename(const char *str);
  774.  
  775. /**
  776.  * Escapes filesystem-unfriendly characters from a filename
  777.  *
  778.  * @param str The string to translate.
  779.  *
  780.  * @return The resulting string.
  781.  */
  782. const char *gaim_escape_filename(const char *str);
  783.  
  784. #ifdef __cplusplus
  785. }
  786. #endif
  787.  
  788. #endif /* _GAIM_UTIL_H_ */
  789.